<HTML>
<TITLE>module damping_driver_mod</TITLE>
<BODY BGCOLOR="#AABBCC" TEXT="#332211" >

<DIV ALIGN="CENTER"> <FONT SIZE=1>
<A HREF="#INTERFACE">PUBLIC INTERFACE</A> / 
<A HREF="#ROUTINES">ROUTINES</A> / 
<A HREF="#NAMELIST">NAMELIST</A> / 
<A HREF="#DIAGNOSTICS">DIAGNOSTICS</A> / 
<A HREF="#CHANGES">CHANGES</A> / 
<A HREF="#ERRORS">ERRORS</A> / 
<A HREF="#REFERENCES">REFERENCES</A> / 
<A HREF="#NOTES">NOTES</A> 
</FONT>
<BR><BR></DIV><HR>


<H2>Module Damping_driver_mod</H2>
<A NAME="HEADER">
<PRE>
     <B>Contact:</B>   Bruce Wyman
     <B>Reviewers:</B>

     <B><A HREF=".doc.log#damping_driver.f90">Tags/Status</A></B>
</PRE>
</A><!-- END HEADER -->
<!--------------------------------------------------------------------->
<A NAME="OVERVIEW">
<HR>
<H4>OVERVIEW</H4>
<!-- BEGIN OVERVIEW -->
<PRE>

     A variety of damping processes are controlled by this module.

</PRE>
</A><!-- END OVERVIEW -->
<!--------------------------------------------------------------------->
<A NAME="DESCRIPTION">
<!-- BEGIN DESCRIPTION -->
<PRE>

     The following damping parameterizations are controlled
     through this module:

       1) Rayleigh damping of momentum fields
       2) Namelist control for gravity wave drag.

     Rayleigh damping uses the following formula:

        d(S)/dt = -D*(S-So)

        where S  = momentum quantity to be damped (u,v) 
              D  = user defined coefficient

        for Rayleigh damping: So = 0.

        The damping coefficient D is specified only for the top level.
        The value of D decreases hyperbolicly with level.
        The following formula is used to determine D at lower levels.

                                P2(1)-P2(k)
           D(k) = D(1) * [ 1. + -----------  ]
                                P2(1)+P2(k)

           P2    = P**2 (pressure squared)
           ..(1) = value at level 1 (top)
           ..(k) = value at level k

</PRE>
</A><!-- END DESCRIPTION -->
<!--------------------------------------------------------------------->
<A NAME="MODULES_USED">
<HR>
<H4>OTHER MODULES USED</H4>
<!-- BEGIN MODULES_USED -->
<PRE>

       mg_drag_mod
     utilities_mod
  diag_manager_mod
  time_manager_mod
     constants_mod

</PRE>
</A><!-- END MODULES_USED -->
<!--------------------------------------------------------------------->
<A NAME="INTERFACE">
<HR>
<H4>PUBLIC INTERFACE</H4>
<!-- BEGIN INTERFACE -->
<PRE>

  use damping_driver_mod  [, only:  damping_driver,
                                    damping_driver_init,
                                    damping_driver_end    ]

  damping_driver      - Called every time step to compute damping terms
                        and/or call gravity wave drag.

  damping_driver_init - Must be called once before damping_driver to
                        initialize the module, read namelist input, and
                        to call initialization routines for other
                        modules used.

  damping_driver_end  - Called at the end of the model run to terminate
                        the damping_driver module and other modules used.

  Notes:
   1) A namelist interface controls runtime options and selects fields
      for diagnostics output.
   2) No other data files are needed.

</PRE>
</A><!-- END INTERFACE -->
<!--------------------------------------------------------------------->
<A NAME="ROUTINES">
<HR>
<H4>PUBLIC ROUTINES</H4>
<!-- BEGIN ROUTINES -->
<PRE>

call damping_driver ( is, js, Time, delt, pfull, phalf, zfull, zhalf,
                      u, v, t, q, r,  udt, vdt, tdt, qdt, rdt,
                      [mask, kbot] )

Input

    is, js      starting i,j indices for the sub-window of the
                global grid   [integer]

    Time        current time  [time_type]

    delt        time step in seconds  [real]

    pfull       pressure (in pascals) at full model levels
                  [real, dimension(:,:,nlev)]

    phalf       pressure (in pascals) at half model levels
                  [real, dimension(:,:,nlev+1)]

    zfull       geopotential height (in meters) at full model levels
                  [real, dimension(:,:,nlev)]

    zhalf       geopotential height (in meters) at half model levels
                  [real, dimension(:,:,nlev+1)]

    u, v        zonal wind (u) and meridional wind (v) in m/s
                  [real, dimension(:,:,nlev)]

    t, q        temperature (t) in deg K, and specific humidity (q)
                in kg vapor/kg air
                  [real, dimension(:,:,nlev)]

    r           multiple <I>ntrace</I> tracer fields at 
                full model levels
                  [real, dimension(:,:,nlev,ntrace)]

Input/Output

    udt, vdt    tendencies for zonal wind (udt) and meridional
                wind (vdt) in m/s2
                  [real, dimension(:,:,nlev)]

    tdt, qdt    temperature tendency (tdt) in degK/scc, and specific
                humidity tendency (qdt) in kg vapor/kg air/sec.
                  [real, dimension(:,:,nlev)]

    rdt         tendency for multiple <I>ntrace</I> tracer fields
                   [real, dimension(:,:,nlev,ntrace)]

Input (Optional)


    mask       mask (1. or 0.) for grid boxes above or below
               the ground, usually only necessary for the step-mountain
               (eta) vertical coordinate  [real, dimension(:,:,nlev)]

    kbot       index of the lowest model level, usually only necessary
               for the step-mountain (eta) vertical coordinate
                 [integer, dimension(:,:)]

----------------------------------------------------------------------

call damping_driver_init (lonb, latb, axes, Time)

input

   lonb      The longitude in radians of the grid box edges.
                [real, dimension(:)]

   latb      The latitude in radians of the grid box edges.
                [real, dimension(:)]

   axes      The axis indices that are returned by previous calls to
             diag_axis_init. The values of this array corresponds to the
             x, y, full (p)level, and half (p)level axes. These are the
             axes that diagnostic fields are output on.
                [integer, dimension(4)]

   Time      The current time.  [time_type]

----------------------------------------------------------------------

  call damping_driver_end

  There are no arguments to this routine.

</PRE>
</A><!-- END ROUTINES -->
<!--------------------------------------------------------------------->
<A NAME="NAMELIST">
<HR>
<H4>NAMELIST</H4>
<!-- BEGIN NAMELIST -->
<PRE>

 <b>&damping_driver_nml</b>

    trayfric      damping time in seconds for Rayleigh damping of
                  momentum fields in the top nlev_rayfric layers
                  (if Trayfric &lt; 0 then time in days)
                     [real, default: Trayfric=0.]

    nlev_rayfric  number of levels at the top of the model where
                  Rayleigh friction of momentum is performed
                  (if trayfric=0. then nlev_rayfric has no effect)
                    [integer, default: nlev_rayfric=1]

    do_mg_drag    flag for mountain gravity wave drag
                    [logical, default: do_mg_drag=.false.]

    do_conserve_energy  If TRUE the heating due to the dissipation of kinetic energy
                        by Rayleigh damping will be computed.
                         [logical, default: do_conserve_energy=.false.]

</PRE>
</A><!-- END NAMELIST -->
<!--------------------------------------------------------------------->
<A NAME="DIAGNOSTICS">
<HR>
<H4>DIAGNOSTIC FIELDS</H4>
<PRE>
Diagnostic fields may be output to a netcdf file by specifying the
module name <b>damping</b> and the desired field names (given below)
in file <b>diag_table</b>. See the documentation for diag_manager.
</PRE>
<!-- BEGIN DIAGNOSTICS -->
<PRE>

Diagnostic fields for module name: <b>damping</b>

   field name     field description
   ----------     -----------------

   udt_rdamp        u wind tendency for Rayleigh damping (m/s2)
   vdt_rdamp        u wind tendency for Rayleigh damping (m/s2)
   tdt_diss_rdamp   Dissipative heating from Rayleigh damping (deg_k/s)
   diss_heat_rdamp  Integrated dissipative heating from Rayleigh damping (W/m2)
   udt_gwd          u wind tendency for gravity wave drag (m/s2)
   vdt_gwd          v wind tendency for gravity wave drag (m/s2)
   tdt_diss_gwd     Dissipative heating from gravity wave drag (deg_k/s)
   diss_heat_gwd    Integrated dissipative heating from gravity wave drag (W/m2)
   taub             base flux for gravity wave drag (kg/m/s2)
   sgsmtn           sub-grid scale topography for gravity wave drag (m)

</PRE>
</A><!-- END DIAGNOSTICS -->
<!--------------------------------------------------------------------->
<A NAME="CHANGES">
<HR>
<H4>CHANGE HISTORY</H4>
<!-- BEGIN CHANGES -->
<PRE>
<B><A HREF=".doc.log#damping_driver.f90">CVS Revision history</A></B>


<B>Changes prior to CVS version control</B>

<b>Changes</b> (1/24/2000)

  * Removed the sponge damping option. This option cannot be considered
    column physics. Several namelist variables and diagnostic fields
    were removed but the interface argument lists did not chnage.
    This option may eventually be added to the dynamical core.

<b>Changes</b> (10/4/1999)

  * MPP version created. Minor changes in open_file, error_mesg,
    and Fortran write statements. Answers should reproduce the
    previous version.

  * Implementation of the new MPP diagnostics package.
    This required major changes to the diagnostic interface and
    the manner in which diagnostics quantities are selected.
    There are additional arguments to several interfaces.

  * There were no changes made that would cause answers to changes.

</PRE>
</A><!-- END CHANGES -->
<!--------------------------------------------------------------------->
<A NAME="ERRORS">
<HR>
<H4>ERROR MESSAGES</H4>
<!-- BEGIN ERRORS -->
<PRE>

damping_driver

    damping_driver_init must be called first

</PRE>
</A><!-- END ERRORS -->
<!--------------------------------------------------------------------->
<A NAME="REFERENCES">
<HR>
<H4>REFERENCES</H4>
<!-- BEGIN REFERENCES -->
<PRE>

     None.

</PRE>
</A><!-- END REFERENCES -->
<!--------------------------------------------------------------------->
<A NAME="BUGS">
<HR>
<H4>KNOWN BUGS</H4>
<!-- BEGIN BUGS -->
<PRE>

     There are no known bugs.

</PRE>
</A><!-- END BUGS -->
<!--------------------------------------------------------------------->
<A NAME="NOTES">
<HR>
<H4>NOTES</H4>
<!-- BEGIN NOTES -->
<PRE>

     None.

</PRE>
</A><!-- END NOTES -->
<!--------------------------------------------------------------------->
<A NAME="PLANS">
<HR>
<H4>FUTURE PLANS</H4>
<!-- BEGIN PLANS -->
<PRE>

     Interface and diagnostics for topographic drag will be added.

</PRE>
</A><!-- END PLANS -->
<!--------------------------------------------------------------------->

<HR>
</BODY>
</HTML>
